[Experimental] Check whether one or more users are authorized to access resources
[Experimental] The Evaluations API allows batch authorization checks in a single request. It supports request-level defaults for subject, action, resource, and context that can be overridden per evaluation item.
Evaluation Semantics
The options.evaluations_semantic field controls how evaluations are processed:
execute_all(default): Execute all evaluations and return all resultsdeny_on_first_deny: Stop processing on first deny decisionpermit_on_first_permit: Stop processing on first permit decision
When using deny_on_first_deny or permit_on_first_permit, the response may include fewer items than the request because processing short-circuits when the condition is met.
Authorization Model Selection
To pin evaluations to a specific authorization model version, send the Openfga-Authorization-Model-Id header. If the header is not provided, the latest model is used.
Examples
Basic batch evaluation
Check if a user can perform multiple actions on a document:
{
"subject": {"type": "user", "id": "anne"},
"resource": {"type": "document", "id": "roadmap"},
"evaluations": [
{"action": {"name": "can_read"}},
{"action": {"name": "can_write"}},
{"action": {"name": "can_delete"}}
]
}
Using evaluation semantics
Stop on first permitted action (useful for finding any valid permission):
{
"subject": {"type": "user", "id": "anne"},
"resource": {"type": "document", "id": "roadmap"},
"evaluations": [
{"action": {"name": "can_read"}},
{"action": {"name": "can_write"}}
],
"options": {
"evaluations_semantic": "permit_on_first_permit"
}
}
Overriding defaults per evaluation
Check permissions across multiple resources:
{
"subject": {"type": "user", "id": "anne"},
"action": {"name": "can_read"},
"evaluations": [
{"resource": {"type": "document", "id": "doc1"}},
{"resource": {"type": "document", "id": "doc2"}},
{"resource": {"type": "folder", "id": "folder1"}}
]
}
# HTTP only: no named client or generated low-level operation in the audited SDK versions.
# Set FGA_API_URL to the URL of your OpenFGA server.
# Set FGA_STORE_ID to your store ID.
# These examples use a server with authentication disabled.
# For authenticated servers, see /docs/getting-started/setup-sdk-client.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/access/v1/evaluations" \
-H "content-type: application/json" \
-d '{
"evaluations": [
{
"subject": {
"type": "user",
"id": "anne"
},
"action": {
"name": "reader"
},
"resource": {
"type": "document",
"id": "budget"
}
}
]
}'{
"evaluations": [
{
"context": {},
"decision": true
}
]
}{
"code": "validation_error",
"message": "Generic validation error"
}{
"code": "unauthenticated",
"message": "unauthenticated"
}{
"code": "forbidden",
"message": "the principal is not authorized to perform the action"
}{
"code": "undefined_endpoint",
"message": "Endpoint not enabled"
}{
"code": "10",
"message": "transaction conflict"
}{
"code": "throttled_timeout_error",
"message": "timeout due to throttling on complex request"
}{
"code": "internal_error",
"message": "Internal Server Error"
}Path Parameters
Body
Show child attributes
Show child attributes
Optional. If omitted or empty, behaves like a single Access Evaluation request.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Response
A successful response.
Show child attributes
Show child attributes
Was this page helpful?
# HTTP only: no named client or generated low-level operation in the audited SDK versions.
# Set FGA_API_URL to the URL of your OpenFGA server.
# Set FGA_STORE_ID to your store ID.
# These examples use a server with authentication disabled.
# For authenticated servers, see /docs/getting-started/setup-sdk-client.
curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/access/v1/evaluations" \
-H "content-type: application/json" \
-d '{
"evaluations": [
{
"subject": {
"type": "user",
"id": "anne"
},
"action": {
"name": "reader"
},
"resource": {
"type": "document",
"id": "budget"
}
}
]
}'{
"evaluations": [
{
"context": {},
"decision": true
}
]
}{
"code": "validation_error",
"message": "Generic validation error"
}{
"code": "unauthenticated",
"message": "unauthenticated"
}{
"code": "forbidden",
"message": "the principal is not authorized to perform the action"
}{
"code": "undefined_endpoint",
"message": "Endpoint not enabled"
}{
"code": "10",
"message": "transaction conflict"
}{
"code": "throttled_timeout_error",
"message": "timeout due to throttling on complex request"
}{
"code": "internal_error",
"message": "Internal Server Error"
}